The OIDC provider ARN placeholder <YOUR_OIDC_ISSUER_HOST> is likely misleading for issuers that include a path (common with Okta/Keycloak). In AWS, the oidc-provider/... segment must match the provider URL without the scheme and including any path; consider renaming the placeholder and clarifying this here.

The docs now instruct users to set spec.type: awsSts with an awsSts: block, but the current CRD reference lists MCPExternalAuthConfigSpec.type enum values without awsSts and doesn’t document an awsSts field (see docs/toolhive/reference/crd-spec.md around the MCPExternalAuthConfigSpec table). Either update the CRD reference (and ensure the operator actually supports awsSts), or gate this tutorial behind the ToolHive version that introduces it.

This tip suggests switching MCPExternalAuthConfig.spec.type to awsSts, but the CRD reference currently doesn’t list awsSts as a supported enum value for MCPExternalAuthConfigSpec.type. Either update the reference/CRD docs alongside this change or add an explicit minimum ToolHive version requirement.

aws iam create-open-id-connect-provider typically requires --thumbprint-list, and the placeholder usage is inconsistent: the command hard-codes https:// but the <YOUR_OIDC_ISSUER> example below includes https://..., which would lead to a doubled scheme if copied literally. Update the command/placeholders to be unambiguous and include the required thumbprint input.

Similarly, the IAM trust policy condition key should match the full OIDC provider identifier (host plus any issuer path) used when creating the provider (for example issuer.example.com/oauth2/default:aud). Clarify that <...>:aud must include the same path portion if present.

This example pipes oauth2c output through jq, but the tutorial doesn’t mention jq as a prerequisite. Add it to prerequisites or show an alternative that doesn’t require jq.

This guide recommends type: awsSts, but the CRD reference currently doesn’t list awsSts as a valid MCPExternalAuthConfigSpec.type value. Please update the CRD reference (or adjust the guidance) so readers don’t end up with manifests rejected by the API server.

This section claims built-in AWS STS support, but the current CRD spec documentation for MCPExternalAuthConfig doesn’t include an awsSts type/config. Please align this concept doc with the actual shipped CRD (or update the CRD reference docs in the same change) to avoid documenting unsupported configuration.

I assume this (and other similar comments from Copilot) are because a release hasn't been cut with these new fields yet? That will auto-update the CRD reference.

The tutorial uses aws CLI commands later, but the prerequisites don’t mention installing/configuring the AWS CLI (and credentials for running IAM commands). Add AWS CLI as an explicit prerequisite so readers can follow Step 1/2 without getting blocked.

This note feels too early, priority doesn't appear until the next section, suggest moving it down to line 291, just after the placeholders but before applying it.

The line highlighting seems off here. The name (since it's referenced later) and type make sense, but guessing the highlight on the blank line is just a one-off miss? In fact since most of it is directly relevant, maybe just highlight the type field? Optionally could also highlight the three lines with placeholders to replace (9,13,19) but that makes it a little staccato to read.

From their docs, I believe the MCP itself only exists in us-east-1, and the region for operations is influenced by a flag on their own proxy wrapper for it, or by the prompt that invokes the tools? I get an NXDOMAIN when I try to resolve the MCP endpoint on any region other than us-east-1.

Worth calling out that this assumes the reader is using a GatewayAPI solution and it would need adjustment for Ingress controllers?

+1 to calling out the specific ngrok guide, we also have the more generic "Connect clients to MCP servers" guide too (../guides-k8s/connect-clients.mdx)

If we're cleaning up, let's clean up 😄

Nit: the "7 of 9 tools" will go stale, maybe not necessary at all or replace with "most tools"?

The explanation here references "the roleClaim JWT claim (here, groups)" but the YAML in Step 3 doesn't include a roleClaim field anywhere. The YAML shows claim: s3-readers under roleMappings, where a reader would naturally parse claim as a claim name rather than a value to match against.

Three things need clarifying:

1. Where does groups come from? If roleClaim is a CRD field that defaults to groups, mention that explicitly — even a YAML comment like # roleClaim defaults to "groups" in the example would help.
2. The claim field under roleMappings represents a value to match, not a claim name — that's counterintuitive and worth a sentence of explanation.
3. Readers whose IdP uses a different claim name (e.g., Auth0 may use roles or a custom namespace instead of groups) need to know how to change it.

Without this, a reader who doesn't happen to have a groups claim in their tokens won't know what to adjust.

Generated by Claude Code

Claude identified this; I'm not as well-versed in the specifics here so take it with a grain of salt 😉

Phase 1 of the restructuring was just merged, so you'll need to rebase to put this in the new integrations sidebar section. The actual file location is fine, those won't move until phase 2.